O Sistema de Pagamentos K8Bank

O objetivo desta documentação é detalhar o sistema K8Bank Pagamentos, que disponibiliza métodos para a realização de pagamentos via Boleto, Cartão de Crédito e Pix, com funcionalidades de checkout completo e transparente e consulta de transações.

1. Endereço de disponibilização

A API para integração está disponível nesta documentação web e também no seguinte endereço: https://sandbox.k8bank.com.br/BknBankPagamentosAPI

No site, é possível buscar pela "Definição em formato Swagger" dos métodos:

Por exemplo, para o método “ConsultaTransacoes”:

Via Swagger você conseguirá visualizar o envio e retorno das chamadas sem criptografia.

Ao final do processo, você deverá solicitar suas credenciais ao nosso time de integração.

2. Funcionamento Geral

O funcionamento geral da integração com o sistema K8Bank Pagamentos é feito através do conceito de “checkout completo” e “checkout transparente”.

No modelo checkout completo, o comércio inicia uma transação no sistema informando os dados gerais e alguns parâmetros necessários, direcionando então ao usuário para uma página do sistema K8BankPagamentos que permite escolher a forma de pagamento (dentro das opções de boleto, cartão de crédito e pix – que podem ser ativadas o inativadas por comércio) e realizar  o referido pagamento, retornando a uma página do comércio ao final do fluxo. O fluxo ainda permite receber uma chamada de confirmação quando o pagamento for finalizado, que é especialmente importante para os casos de boleto e pix, que são resolvidos depois da criação da transação, e permite ainda definir diversas condições adicionais de pagamento, como desconto no caso de boleto e no caso de pix, além de permitir customizar o valor no cartão de crédito para pagamento a vista, parcelado via lojista e parcelado via emissor.

No modelo checkout transparente, o pagamento é realizado totalmente no site do comércio, que é responsável por solicitar a forma de pagamento desejada, solicitar os parâmetros desejados do usuário (como os dados do cartão de crédito) e iniciar a transação na API do sistema K8Bank Pagamentos. Neste caso, existe a posibilidade de realizar as operações via Boleto, Cartão de Crédito e Pix, em métodos separados da API, e ainda a possibilidade de realizar pagamentos com split de valores, que permitem creditar automaticamente diversas contas K8Bank em um único pagamento, sem a necessidade de repasse posterior dos valores.  Os métodos de checkout transparente via Boleto e Pix também apresentam a possibilidade de definir uma URL de confirmação do comércio, que será chamada quando  o pagamento for finalizado (aprovado ou cancelado).

A API disponibiliza ainda métodos que permitem aos comércios consultar por transações em faixas de data, de determinados tipos e em determinados estados e ainda obter todos os detalhes de uma transação específica.

O diagrama de sequeência para cada um dos fluxos pode ser visto abaixo:

Fluxo de Checkout completo

Fluxo de Checkout transparente – pagamento via Boleto

Fluxo de Checkout transparente – pagamento via Cartão de Crédito

Fluxo de Checkout transparente – pagamento via Pix

3. Requisitos de Segurança

Para garantir a segurança das operações, a API do sistema K8Bank Pagamentos utiliza três mecanismos principais:

- autenticação no padrão OAuth2 no fluxo tipo “Bearer Token”, o qual funciona através do envio de um token no header “Authorization” de cada chamada posterior a autenticação.
Os tokens devem ser obtidos através de um método especial da API “token”, com o envio de um clientId (usuário) e clientSecret (senha) como parâmetro, sendo que estes são gerados de forma exclusiva para cada comércio e que possuem uma determinada validade após a qual devem ser renovados, notando que as chamadas realizadas sem informar um token ou com um token vencido retornam o erro HTTP 401 Unauthorized. Notar que é tarefa do desenvolvimento do comércio gestionar os tokens e a respectiva renovação dos mesmos;

- criptografia completa das requisições e respostas das mensagens no padrão AES-128, com uma chave definida de forma exclusiva para cada comércio, com o intuito de aperfeiçoar a segurança do sistema. O IV (vetor de inicialização) utilizado é vazio. Ou seja, corresponde a 16 bytes com valor 0;

- validação do endereço IP de origem das chamadas, que pode ser configurado de forma opcional para cada comércio, sendo recomendado para maior segurança nos casos aonde as chamadas de saída apresentem tão somente um único IP.

4. Forma de Uso

Para uso da API, é necessário acessar a interface gráfica do sistema K8Bank Pagamentos, no endereço https://sandbox.k8bank.com.br

Logar no sistema e gerar um acesso, na opção de menu “Acesso”:

Caso seja o primeiro acesso, clicar no botão “Gerar Credenciais de acesso”, que gera valores para os campos “Client Id”, “Client Secret” e “Chave AES”.

Se desejado, é possível especificar um IP fixo que terá permissão de uso na API, ou utilizar IP dinâmico, que é menos seguro e recomendado durante o desenvolvimento da integração com o sistema de pagamentos;

Para testar interativamente a chamada de um método da API, sem a necessidade de desenvolver código, expandir o nome do método desejado:

Clicar no ícone   no lado superior direito:

Informar o valor do campo “Client Id” como sendo o Username e o campo “Client Secret” como sendo o Password:

Marcar a checkbox “BknBankPagamentosAPI” e clicar no botão “Authorize”.
Se os dados foram informados corretamente, o ícone ser exibido em azul: .

Agora, informar a requisição a ser enviada no campo “Request”.

Por exemplo:

{

"DataHoraInicial": "2021-02-01 T00:00:00",

"DataHoraFinal": "2021-02-26T23:59:59",

"Tipo": "Cartao",

"Estado": "Aprovada"

}

Informar no campo AESKey o valor do parâmetro “Chave AES”:

Clicar no botão “Try it out!”:

A resposta da chamada é exibida na janela “Response Body”.

5. Formas de uso da API

A API pode ser utilizada das seguintes formas:

- Integração direta do comércio com a API mediante desenvolvimento de software próprio, em tecnologia e linguagem de programação a escolha, utilizando a documentação fornecida, e atentando aos requisitos de segurança.

- Integração via SDKs disponibilizadas nas tecnologias .NET (C#), Java, PHP, NodeJS (Javascript/Typescript) ou Python. Notar que as SDKs já realizam todos os tratamentos necessários, incluindo os requisitos de segurança (OAuth2/criptografia AES128) e permitem o desenvolvimento mais rápido da integração.

- Plugins para integração dos sistemas de e-commerce Magento e Prestashop, que já possuem todo o código necessário para a integração, necessitando tão somente da configuração do módulo.